More docs for sumdb - #46
Merged
Merged
Conversation
mhutchinson
force-pushed
the
moredocs
branch
from
September 25, 2025 09:24
e4b03d9 to
ee4e38e
Compare
mhutchinson
force-pushed
the
moredocs
branch
from
September 25, 2025 09:31
ee4e38e to
1c77442
Compare
AlCutter
reviewed
Sep 25, 2025
| [Tessera]: https://github.com/transparency-dev/tessera | ||
| ### Background | ||
|
|
||
| The sum.golang.org service, often referred to as Go Checksum DB or SumDB, serves as an auditable checksum database for Go modules. Its primary purpose is to enhance the security and integrity of the Go module ecosystem by providing a public, tamper-proof record of module checksums. This ensures that when developers fetch a module, they receive the exact version of the code that others are using and that hasn't been maliciously altered. |
Contributor
There was a problem hiding this comment.
Suggested change
| The sum.golang.org service, often referred to as Go Checksum DB or SumDB, serves as an auditable checksum database for Go modules. Its primary purpose is to enhance the security and integrity of the Go module ecosystem by providing a public, tamper-proof record of module checksums. This ensures that when developers fetch a module, they receive the exact version of the code that others are using and that hasn't been maliciously altered. | |
| The sum.golang.org service, often referred to as Go Checksum DB or SumDB, serves as an auditable checksum database for Go modules. Its primary purpose is to enhance the security and integrity of the Go module ecosystem by providing a public, tamper-proof record of module checksums. This ensures that when developers fetch a module, they receive the exact version of the code that others are using and that hasn't been maliciously altered in transit. |
Contributor
Author
There was a problem hiding this comment.
Not sure about this one - it could have also been altered at rest?
Contributor
There was a problem hiding this comment.
That was more of an example, I should've been clearer - currently it kinda reads like "everyone gets something which isn't malicious", but could be made clearer by either trimming to be "... the exact version of the code that others are using." or it needs some sort of clarifying qualification (which is what I mean by "more of an example").
Comment on lines
+14
to
+28
| In addition to sum.golang.org, there is also an index at index.golang.org. This index provides a convenient way to discover available Go modules and their versions. However, it's important to note that index.golang.org is not verifiable in the same way as sum.golang.org. While it helps with discovery, it does not offer the same cryptographic guarantees of integrity and immutability as the checksum database. The security and verification of module content rely solely on the auditable records within sum.golang.org. | ||
|
|
||
| The entries in the SumDB log match what is written in a `go.sum` file. | ||
| For example, any project depending on the v1.0 release of Tessera will have the following in its `go.sum` file: | ||
|
|
||
| ``` | ||
| github.com/transparency-dev/tessera v1.0.0 h1:4OT1V9xJLa5NnYlFWWlCdZkCm18/o12rdd+bCTje7XE= | ||
| github.com/transparency-dev/tessera v1.0.0/go.mod h1:TLvfjlkbmsmKVEJUtzO2eb9Q2IBnK3EJ0dI4G0oxEOU= | ||
| ``` | ||
|
|
||
| This is the same content written to the SumDB at index 43930254 ([query link](https://sum.golang.org/lookup/github.com/transparency-dev/tessera@v1.0.0)). | ||
|
|
||
| The index is built from this log of modules by parsing the module name from every leaf. A pointer to the leaf is added to the index if it represents a [non-pseudo](https://pkg.go.dev/golang.org/x/mod@v0.28.0/module#IsPseudoVersion) version. | ||
| The index can be [queried](#querying) using the client. | ||
|
|
Contributor
There was a problem hiding this comment.
The flow of this section could be improved. Currently it jumps around a lot - I think the para about index.golang.org is the culprit, could this be moved down to replace/incorporate the "The index is built from this log ..." bit?
Contributor
Author
There was a problem hiding this comment.
Reworked, PTAL?
| ``` | ||
|
|
||
| Use left/right cursor to browse, and `q` to quit. | ||
| Note that this matches the list of entries on the unverifiable proxy endpoint: https://proxy.golang.org/github.com/transparency-dev/tessera/@v/list. |
Contributor
There was a problem hiding this comment.
Would probably be good to introduce the proxy service in the background bit too?
AlCutter
approved these changes
Sep 25, 2025
mhutchinson
commented
Sep 25, 2025
| [Tessera]: https://github.com/transparency-dev/tessera | ||
| ### Background | ||
|
|
||
| The sum.golang.org service, often referred to as Go Checksum DB or SumDB, serves as an auditable checksum database for Go modules. Its primary purpose is to enhance the security and integrity of the Go module ecosystem by providing a public, tamper-proof record of module checksums. This ensures that when developers fetch a module, they receive the exact version of the code that others are using and that hasn't been maliciously altered. |
Contributor
Author
There was a problem hiding this comment.
Not sure about this one - it could have also been altered at rest?
Comment on lines
+14
to
+28
| In addition to sum.golang.org, there is also an index at index.golang.org. This index provides a convenient way to discover available Go modules and their versions. However, it's important to note that index.golang.org is not verifiable in the same way as sum.golang.org. While it helps with discovery, it does not offer the same cryptographic guarantees of integrity and immutability as the checksum database. The security and verification of module content rely solely on the auditable records within sum.golang.org. | ||
|
|
||
| The entries in the SumDB log match what is written in a `go.sum` file. | ||
| For example, any project depending on the v1.0 release of Tessera will have the following in its `go.sum` file: | ||
|
|
||
| ``` | ||
| github.com/transparency-dev/tessera v1.0.0 h1:4OT1V9xJLa5NnYlFWWlCdZkCm18/o12rdd+bCTje7XE= | ||
| github.com/transparency-dev/tessera v1.0.0/go.mod h1:TLvfjlkbmsmKVEJUtzO2eb9Q2IBnK3EJ0dI4G0oxEOU= | ||
| ``` | ||
|
|
||
| This is the same content written to the SumDB at index 43930254 ([query link](https://sum.golang.org/lookup/github.com/transparency-dev/tessera@v1.0.0)). | ||
|
|
||
| The index is built from this log of modules by parsing the module name from every leaf. A pointer to the leaf is added to the index if it represents a [non-pseudo](https://pkg.go.dev/golang.org/x/mod@v0.28.0/module#IsPseudoVersion) version. | ||
| The index can be [queried](#querying) using the client. | ||
|
|
Contributor
Author
There was a problem hiding this comment.
Reworked, PTAL?
Contributor
Author
|
I've got a better tool for SumDB module authors in a branch that builds on this one: https://github.com/transparency-dev/incubator/compare/main...mhutchinson:incubator:sumdb-fulltool?expand=1 I'll turn that into a PR when this is merged. |
AlCutter
approved these changes
Sep 25, 2025
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.